home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 1 Issue 2 / PDCD-1 - Issue 02.iso / _utilities / utilities / 004 / dynamite / DynManText < prev    next >
Text File  |  1994-10-21  |  28KB  |  1,015 lines
  1.                     _
  2.                    / \         ___   ___   _____   ╖  /_  __
  3.                   /   ) /   / /   ) /   ) /  /  ) /  /   /__)
  4.                  /___/ (___/ /   ( (___( /  /  ( (_ (_  (___
  5.                       ____/
  6.  
  7.                               Programmer's Guide
  8.  
  9.  
  10.  
  11.                                   Straylight
  12.  
  13.                   16 Portland Street, Royal Leamington Spa,
  14.                             Warwickshire, CV32á5HE
  15.  
  16.                     Telephone and facsimile: 01926á452639
  17. _____________________________________________________________________________
  18.  
  19.         ⌐ 1994 Straylight
  20.  
  21.         This documentation refers to Dynamite module version 1.10
  22.  
  23.         The Dynamite software and accompanying documentation are to be
  24.         considered as `Freeware' -- they may be reproduced and distributed on
  25.         condition that they are not altered in any way and no profit is made
  26.         by so doing.  You may supply the Dynamite module with any software
  27.         which uses it, including software for which a profit is made.
  28.  
  29.         Because the program is licensed free of charge, there is no warranty
  30.         for the program, to the extent permitted by applicable law.  Except
  31.         when otherwise stated in writing the copyright holders and/or other
  32.         parties provide the program `as is' without warranty of any kind,
  33.         either expressed or implied, including, but not limited to, the
  34.         implied warranties of merchantability and fitness for a particular
  35.         purpose.  The entire risk as to the quality and performance of the
  36.         program is with you.  Should the program prove defective, you assume
  37.         the cost of all necessary servicing, repair or correction.
  38.  
  39.         The product described in this documentation is the subject of
  40.         continual development and, while all efforts are taken to ensure
  41.         that the information given is correct, Straylight cannot accept any
  42.         liability for loss or damage resulting from the use or misuse of this
  43.         product.
  44.  
  45. Trademarks
  46.  
  47.         Acorn, Archimedes and RISC PC are trademarks of Acorn Computers Ltd.
  48.         ARM is a trademark of Advanced RISC Machines Ltd.
  49.  
  50.         All other trademarks acknowledged.
  51. _____________________________________________________________________________
  52.  
  53. Dynamite overview
  54.  
  55.  
  56. What does Dynamite do?
  57.  
  58.         One of the greatest problems facing module writers is that of
  59.         allocating memory.  Although the Relocatable Module Area has been
  60.         provided to allow modules to allocate workspace, its design causes
  61.         it to fragment over a period of time.
  62.  
  63.         Programmers have been aware of this problem for a long time, and
  64.         several have started to use the System Sprite Area as an alternative
  65.         source of memory, since it does not suffer from fragmentation in the
  66.         same way as the RMA.
  67.  
  68.         Acorn have finally addressed this difficulty and enabled modules
  69.         running under RISCáOS 3.5 or later to create their own dynamic areas,
  70.         which they can then manage themselves, for example, by implementing a
  71.         shifting heap similar to that used by most applications.
  72.         Unfortunately this solution is not available to programs required to
  73.         run on machines earlier than the RISCáPC.
  74.  
  75.         Dynamite is a small module which provides a solution to the problem
  76.         of memory allocation without causing fragmentation of the RMA,
  77.         abusing the Sprite area, or being specific to any particular
  78.         operating system versions.  This means that code which uses Dynamite
  79.         should be able to run on any version of RISCáOS.
  80.  
  81.         Running under RISCáOS 3.5 or later, Dynamite creates its own dynamic
  82.         area and implements within it a shifting heap which is compacted over
  83.         a period of time by a WIMP task.
  84.  
  85.         Under earlier versions of RISCáOS, Dynamite shuffles the memory map
  86.         to create its own `dynamic area', and implements within it a
  87.         shifting heap as before.
  88.  
  89.         The interface to the Dynamite memory manager is identical, whether or
  90.         not a real dynamic area is used.  Since blocks are always allocated
  91.         within Dynamite's special area of memory, clients which require
  92.         blocks of memory and can cope with them being moved around can now
  93.         obtain them without fragmenting the RMA.
  94.  
  95.  
  96. How Dynamite works
  97.  
  98.   Operation under RISCáOS 3.5 or later
  99.  
  100.         Dynamite's operation under RISCáOS 3.5 is fairly simple -- the new
  101.         facilities provided by OS_DynamicArea are used to create and resize
  102.         the heap as required.
  103.  
  104.   Operation under RISCáOS versions prior to 3.5
  105.  
  106.         Since early versions of RISCáOS do not provide calls for creating
  107.         dynamic areas, Dynamite takes matters into its own hands.  It uses
  108.         the area of logical memory at the end of the System Sprite area (up
  109.         to &01800000) to build its heap.
  110.  
  111.         Normally, the System Sprite Area is layed out as shown below:
  112.  
  113.                         [Picture: DynManDocs.Diag_1/1]
  114.  
  115.         Only the shaded area used by the system sprites actually has physical
  116.         memory pages associated with it.
  117.  
  118.         Dynamite creates its area at the other end of the System Sprite Area,
  119.         from 24M downwards, as shown overleaf.
  120.  
  121.                         [Picture: DynManDocs.Diag_1/2]
  122.  
  123.         Operating system routines are intercepted to ensure that Dynamite's
  124.         maintenance of this area does not affect the normal operation of the
  125.         kernel's memory management.
  126.  
  127.         It should be noted that because of this method of implementation,
  128.         there is a limit of 4M (assuming there are no System Sprites) on the
  129.         size of Dynamite's heap.  The RMA also has a limit of 4M, and this
  130.         is rarely exceeded, so this is unlikely to cause a problem in
  131.         practice.
  132.  
  133.         It should be noted that the Task Manager will show the size of the
  134.         Sprite area including Dynamite's area.  However, OS_ReadDynamicArea
  135.         will return only the amount occupied by the System Sprites, allowing
  136.         programs which use sprites to store their data to work as before.
  137.         OS_ChangeDynamicArea will continue to work as before; only the area
  138.         containing the System Sprites will change in size.
  139.  
  140.         Warning: To the best of our knowledge, there are no other programs
  141.         which use the area of memory at the end of the Sprite area.  If
  142.         similar modules appear, there are likely to be severe compatibility
  143.         problems.  It is for this reason that we have decided to publish the
  144.         interface to Dynamite.
  145. _____________________________________________________________________________
  146.  
  147. Using Dynamite
  148.  
  149.  
  150. Who can use Dynamite?
  151.  
  152.         Straylight have decided to make this module `freeware'.  It remains
  153.         at all times Copyright ⌐ 1994 Straylight, however it may be
  154.         distributed with products which wish to use it, whether or not they
  155.         are commercial.  No charge may be made for Dynamite specifically,
  156.         and the module must not be altered in any way.
  157.  
  158.         All products distributed with Dynamite must state in the main
  159.         documentation that Dynamite is ⌐ 1994 Straylight.
  160.  
  161.  
  162. Loading Dynamite
  163.  
  164.         Dynamite should normally be loaded from an Obey file in the following
  165.         way:
  166.  
  167.                 RMEnsure Dynamite 0.00 RMRun <My$Dir>.Dynamite
  168.                 RMEnsure Dynamite 1.10 Error 0 Dynamite module is too old
  169.  
  170.         It is important to note that the Dynamite module must be RMRun, not
  171.         just RMLoaded -- this will ensure that the Dynamite WIMP task is
  172.         started correctly.
  173. _____________________________________________________________________________
  174.  
  175. About the Dynamite heap
  176.  
  177.  
  178. Shifting heaps
  179.  
  180.         Dynamite allocates blocks from a shifting heap.  This means that
  181.         blocks allocated from the heap will be moved around in order to
  182.         close up any gaps created by freeing blocks.  In a normal heap, for
  183.         example that implemented by OS_Heap or the C library's malloc
  184.         function, the free memory in the heap can become fragmented.  For
  185.         example, consider a heap from which 3 blocks have been allocated:
  186.  
  187.                         [Picture: DynManDocs.Diag_3/1]
  188.  
  189.         The lower area of the heap has been allocated, but there is a chunk
  190.         of free memory at the end, which can be claimed.  If block 2 is now
  191.         freed, the heap would look like this:
  192.  
  193.                         [Picture: DynManDocs.Diag_3/2]
  194.  
  195.         There are now two free areas which memory may be allocated, but since
  196.         they are not contiguous, the size of the largest block which can be
  197.         allocated is dictated by the size of the largest free area.  If the
  198.         free space could be coalesced in some way, then obviously all the
  199.         free space in the heap is available for allocation.
  200.  
  201.         Clearly, the only way to gather these free areas together is by
  202.         moving the allocated blocks.  It is this property which defines the
  203.         shifting heap.  The problem with a shifting heap is that the blocks
  204.         allocated in it can move whenever free space is generated within the
  205.         heap.  Programs making use of such a memory manager must be able to
  206.         cope with this.
  207.  
  208.  
  209. Dynamite's memory manager
  210.  
  211.         Dynamite implements a shifting heap within its dynamic area.  As a
  212.         result, programs making use of Dynamite must be able to deal with
  213.         their blocks of memory being moved.  Since Dynamite may be used by
  214.         multiple clients, each must be aware that its blocks may be shifted
  215.         while it does not have control of the processor.  For each block you
  216.         allocate, you must tell Dynamite the address of your pointer to the
  217.         block.  This pointer is called the block's anchor pointer.  This is
  218.         so that Dynamite can update your anchor when the block moves.  Note
  219.         that you should not put anchors into application memory, since
  220.         Dynamite may have to update them while your application is paged out.
  221.         To make this easier, Dynamite allows you to allocate anchors from the
  222.         RMA very easily.  You can then store the address of the anchor in
  223.         your own memory.
  224.  
  225.         You should always address a Dynamite block through its anchor
  226.         pointer, rather than taking copies of the block address.  If you
  227.         don't do this, Dynamite will correctly update the block's anchor
  228.         should the block move, leaving any other copies of the address
  229.         unchanged.  Of course, you can assume that pointers remain valid
  230.         while you have control, but e.g.  calling Wimp_Poll may cause them to
  231.         be invalidated, since Dynamite uses idle events to compact the heap.
  232.  
  233.  
  234. Using Dynamite from interrupt routines
  235.  
  236.         Most Dynamite routines are not re-entrant, so you should request a
  237.         callback before using them.  You must also take into account that the
  238.         foreground application may have pointers to Dynamite blocks tem
  239.         porarily in registers or on the stack etc., which you should ensure
  240.         remain valid.  To assist you in this, Dynamite will normally only
  241.         move blocks which you explicitly resize.  However, if enough memory
  242.         is not available, Dynamite will attempt to compact the heap.  You
  243.         must therefore disable this using the SWI Dynamite_Lock.
  244.  
  245.         As long as the foreground task is guaranteed to not have access to
  246.         blocks used by your callback routine, or it has been written to cope
  247.         with this, then you will not have any problems.
  248.  
  249. Using Dynamite from SWIs
  250.  
  251.         You should take careful note of the points raised in the previous
  252.         section when writing SWI handlers which use Dynamite, since your SWI
  253.         may well be called from a callback routine.
  254.  
  255.  
  256. Using Dynamite from command line applications
  257.  
  258.         You must be aware that the user may want to run your command line
  259.         application within a TaskWindow.  This may cause your application to
  260.         lose control of the processor at arbitrary points within your
  261.         program, during which time, the rest of the desktop is active.  This
  262.         means that other applications may cause blocks to move within the
  263.         Dynamite heap -- in particular, Dynamite may be compacting the heap
  264.         during this time.  To prevent this from happening, you should lock
  265.         the heap while you are accessing Dynamite blocks and unlock it again
  266.         when you have finished, using the relevant SWIs.
  267.  
  268.  
  269. The Dynamite relocation stack
  270.  
  271.         To help you keep track of blocks when they move, you can save
  272.         pointers on a special stack.  When you load the pointers back, they
  273.         will have been relocated so that they still point at the same data
  274.         object, even if it was within a Dynamite block which has been moved.
  275.  
  276.  
  277. Block IDs
  278.  
  279.         When you allocate a block using Dynamite_Alloc, you can specify a
  280.         block ID to associate with it.  This can be any 32-bit value you
  281.         like, although it should be something unlikely to conflict with
  282.         other client's IDs, e.g.:
  283.  
  284.         * A module's base address
  285.  
  286.         * An application's task handle or start time
  287.  
  288.         If you want your program to have multiple IDs, you could divide the
  289.         ID value into a `magic' field (say 24 bits of module base address)
  290.         and an index number.
  291.  
  292.         Later, you can free all blocks with a particular ID.  This is useful
  293.         when you want to free all the blocks associated with a particular
  294.         object when that object is destroyed.  For example, during
  295.         development of a module, you could free all its Dynamite blocks in
  296.         the finalisation code.
  297.  
  298.  
  299. Compaction of the Dynamite heap
  300.  
  301.         The Dynamite module has a WIMP task which will partially tidy the
  302.         heap while the processor is idle.  This means that the process of
  303.         removing free space from the heap is distributed over a period of
  304.         time, and will probably not be noticeable in average use.
  305.  
  306.         If you are writing a program which will not multitask, you should
  307.         perform this tidying yourself from time to time, using the
  308.         appropriate Dynamite SWIs.
  309. _____________________________________________________________________________
  310.  
  311. SWI calls
  312.  
  313.  
  314. Standard features
  315.  
  316.         Dynamite SWIs obey the following conventions:
  317.  
  318.         * Arguments are passed in registers, starting from R0.  Return values
  319.          are also given in registers.
  320.  
  321.         * All registers not explicitly used to return results are preserved.
  322.  
  323.         * On exit, the V flag is used to indicate an error status.  The carry
  324.           flag may be used to return information as well, although this is
  325.           documented with the appropriate SWIs when it happens.  In all other
  326.           cases, the C, N and Z flags are preserved when there is no error.
  327.  
  328.  
  329. Dynamite_Alloc (SWI &4A3C0)
  330.  
  331.         Allocates a block of memory from the Dynamite heap
  332.  
  333. On entry
  334.  
  335.         R0 = address of block anchor
  336.         R1 = size of block to allocate, in bytes
  337.         R2 = block ID, or 0 for none
  338.  
  339. On exit
  340.  
  341.         R0, R1 preserved
  342.         R2 = address of allocated block
  343.  
  344. Interrupts
  345.  
  346.         Interrupt status is undefined
  347.         Fast interrupts are enabled
  348.  
  349. Processor mode
  350.  
  351.         Processor is in SVC mode
  352.  
  353. Re-entrancy
  354.  
  355.         SWI is not re-entrant
  356.  
  357. Use
  358.  
  359.         This SWI allocates a block from the Dynamite heap.
  360.  
  361.         This SWI may cause blocks to move within the Dynamite heap.
  362.  
  363. Related SWIs
  364.  
  365.         * Dynamite_Free
  366.  
  367.  
  368. Dynamite_Free (SWI &4A3C1)
  369.  
  370.         Frees a Dynamite block, releasing the memory it used
  371.  
  372. On entry
  373.  
  374.         R0 = pointer to anchor of block to be freed
  375.  
  376. On exit
  377.  
  378.         --
  379.  
  380. Interrupts
  381.  
  382.         Interrupt status is not defined
  383.         Fast interrupts are enabled
  384.  
  385. Processor mode
  386.  
  387.         Processor is in SVC mode
  388.  
  389. Re-entrancy
  390.  
  391.         SWI is not re-entrant
  392.  
  393. Use
  394.  
  395.         This SWI will free a block in the Dynamite heap, releasing the memory
  396.         it used for later reallocation.  The free memory will later be
  397.         returned to the operating system during compaction.
  398.  
  399. Related SWIs
  400.  
  401.         * Dynamite_Alloc
  402.         * Dynamite_FreeWithID
  403.  
  404.  
  405. Dynamite_FreeWithID (SWI &4A3C2)
  406.  
  407.         Frees all blocks with a given block ID
  408.  
  409. On entry
  410.  
  411.         R0 = block ID (must be non-zero)
  412.  
  413. On exit
  414.  
  415.         --
  416.  
  417. Interrupts
  418.  
  419.         Interrupt status is not defined
  420.         Fast interrupts are enabled
  421.  
  422. Processor mode
  423.  
  424.         Processor is in SVC mode
  425.  
  426. Re-entrancy
  427.  
  428.         SWI is not re-entrant
  429.  
  430. Use
  431.  
  432.         This SWI will free all blocks which have a specified block ID.
  433.  
  434. Related SWIs
  435.  
  436.         * Dynamite_Free
  437.  
  438.  
  439. Dynamite_BlockInfo (SWI &4A3C3)
  440.  
  441.         Returns information about a Dynamite block
  442.  
  443. On entry
  444.  
  445.         R0 = address of block anchor
  446.  
  447. On exit
  448.  
  449.         R0 preserved
  450.         R1 = address of block
  451.         R2 = current size of block, in bytes
  452.         R3 = block ID, as passed to Dynamite_Alloc
  453.  
  454. Interrupts
  455.  
  456.         Interrupt status is not defined
  457.         Fast interrupts are enabled 
  458.  
  459. Processor mode
  460.  
  461.         Processor is in SVC mode
  462.  
  463. Re-entrancy
  464.  
  465.         SWI is re-entrant
  466.  
  467. Use
  468.  
  469.         This SWI returns various pieces of information about a Dynamite
  470.         block.
  471.  
  472.         The size in R2 is the byte aligned size given to Dynamite_Alloc when 
  473.         the block was created, possibly altered subsequently by
  474.         Dynamite_Resize or Dynamite_MidExtend.
  475.  
  476. Related SWIs
  477.  
  478.         None
  479.  
  480.  
  481. Dynamite_ChangeID (SWI &4A3C4)
  482.  
  483.         Changes the ID of a given block, or all blocks with a given ID
  484.         
  485. On entry
  486.  
  487.         R0 = address of anchor for block, or 0 for all blocks
  488.         R1 = new ID
  489.         R2 = old ID (if R0 = 0)
  490.  
  491. On exit
  492.  
  493.         Ö
  494.         
  495. Interrupts
  496.  
  497.         Interrupt status is not defined
  498.         Fast interrupts are enabled
  499.         
  500. Processor mode
  501.  
  502.         Processor is in SVC mode
  503.         Re-entrancy
  504.         SWI is not re-entrant
  505.         
  506. Use
  507.  
  508.         This SWI will change the ID of the block whose anchor is passed in
  509.         R0, or the ID of all the blocks which have the ID passed in R2,
  510.         if R0 = 0.
  511.         
  512. Related SWIs
  513.  
  514.         None
  515.  
  516.  
  517. Dynamite_Resize (SWI &4A3C5)
  518.  
  519.         Alters the size of a Dynamite block
  520.  
  521. On entry
  522.         R0 = address of block anchor
  523.         R1 = new size of block, in bytes
  524.  
  525. On exit
  526.  
  527.         R0 preserved
  528.         R1 = address of block, which may have moved
  529.  
  530. Interrupts
  531.  
  532.         Interrupt status is not defined
  533.         Fast interrupts are enabled
  534.  
  535. Processor mode
  536.  
  537.         Processor is in SVC mode
  538.  
  539. Re-entrancy
  540.  
  541.         SWI is not re-entrant
  542.  
  543. Use
  544.  
  545.         This SWI will change a block's size.  The exact behaviour of this
  546.         routine depends on whether the new size is greater than or less than
  547.         the old size.  If you are reducing the size of a block, bytes will be
  548.         removed from the end.  Out-of-memory errors will not be returned.
  549.  
  550.         If you are extending a block, bytes are added at the end.  An out-of-
  551.         memory error may be returned if there is not enough memory to extend
  552.         the block.
  553.  
  554.         This SWI may cause blocks to move within the Dynamite heap.
  555.  
  556. Related SWIs
  557.  
  558.         * Dynamite_MidExtend
  559.  
  560.  
  561. Dynamite_MidExtend (SWI &4A3C6)
  562.  
  563.         Inserts or deletes bytes at a given offset within a block
  564.  
  565. On entry
  566.  
  567.         R0 = address of block anchor
  568.         R1 = offset within block to add or remove bytes
  569.         R2 = signed number of bytes to add
  570.  
  571. On exit
  572.  
  573.         R0 preserved
  574.         R1 = address of block, which may have moved
  575.  
  576. Interrupts
  577.  
  578.         Interrupt status is not defined
  579.         Fast interrupts are enabled
  580.  
  581. Processor mode
  582.  
  583.         Processor is in SVC mode
  584.  
  585. Re-entrancy
  586.  
  587.         SWI is not re-entrant
  588.  
  589. Use
  590.  
  591.         This call will, depending on whether R2 is positive or negative,
  592.         insert or remove bytes from a Dynamite block starting at the offset
  593.         given in R1.  This may of course cause the block's size to change.
  594.         Always after a call to Dynamite_MidExtend, the data that was
  595.         previously at offset R1 is moved to offset R1+R2.
  596.  
  597.         The diagrams below show the effects of inserting or removing bytes
  598.         from a block:
  599.  
  600.                         [Picture: DynManDocs.Diag_4/1]
  601.  
  602.         Diagram 1: Inserting bytes
  603.  
  604.                         [Picture: DynManDocs.Diag_4/2]
  605.  
  606.         Diagram 2: Removing bytes
  607.  
  608.         This SWI may cause blocks to move within the Dynamite heap.
  609.  
  610. Related SWIs
  611.  
  612.         * Dynamite_Resize
  613.  
  614.  
  615. Dynamite_Save (SWI &4A3C7)
  616.  
  617.         Saves some registers on Dynamite's relocation stack
  618.  
  619. On entry
  620.  
  621.         R0 = bit mask of registers to save
  622.         Other registers as described below
  623.  
  624. On exit
  625.  
  626.         --
  627.  
  628. Interrupts
  629.  
  630.         Interrupt status is not defined
  631.         Fast interrupts are enabled
  632.  
  633. Processor mode
  634.  
  635.         Processor is in SVC mode
  636.  
  637. Re-entrancy
  638.  
  639.         SWI is not re-entrant
  640.  
  641. Use
  642.  
  643.         This SWI will save the registers specified in R0 on Dynamite's
  644.         relocation stack.  R0 should contain a bit set for each register
  645.         that you want saved -- i.e.  bit 1 set to save R1, etc.
  646.  
  647.         You cannot usefully save R9-R15 or R0, so the corresponding bits of
  648.         R0 should not be set on entry.
  649.  
  650.         The stack is ascending, and follows the normal ARM rules for
  651.         ascending stacks.  Hence if you save R1-R7 on the stack, the saved
  652.         R7 will be the first register to be removed.
  653.  
  654.         The upper two bytes of R0 are ignored by this SWI.  Therefore R0 on
  655.         entry can actually contain an STM instruction specifying the required
  656.         registers.
  657.  
  658. Related SWIs
  659.  
  660.         * Dynamite_Load
  661.  
  662.  
  663. Dynamite_Load (SWI &4A3C8)
  664.  
  665.         Restores registers from Dynamite's relocation stack
  666.  
  667. On entry
  668.  
  669.         R0 = bit mask of registers to load
  670.  
  671. On exit
  672.  
  673.         As described below
  674.  
  675. Interrupts
  676.  
  677.         Interrupt status is not defined
  678.         Fast interrupts are enabled
  679.  
  680. Processor mode
  681.  
  682.         Processor is in SVC mode
  683.  
  684. Re-entrancy
  685.  
  686.         SWI is not re-entrant
  687.  
  688. Use
  689.  
  690.         This SWI will load the registers specified in R0 from Dynamite's
  691.         relocation stack.  R0 should contain a bit set for each register that
  692.         you want loaded -- i.e.  bit 1 set to load R1, etc.
  693.  
  694.         You must not load R9-R15, so the corresponding bits of R0 should not
  695.         be set on entry.
  696.  
  697.         The stack is ascending, and follows the normal ARM rules for
  698.         ascending stacks.  Hence if you save R1-R7 on the stack, the saved
  699.         R7 will be the first register to be removed.
  700.  
  701.         The upper two bytes of R0 are ignored by this SWI.  Therefore R0 on
  702.         entry can actually contain an LDM instruction specifying the required
  703.         registers.
  704.  
  705. Related SWIs
  706.  
  707.         * Dynamite_Save
  708.  
  709.  
  710. Dynamite_Reduce (SWI &4A3C9)
  711.  
  712.         Performs a partial compaction of the Dynamite heap
  713.  
  714. On entry
  715.  
  716.         --
  717.  
  718. On exit
  719.  
  720.         C set if no compaction performed, clear otherwise
  721.  
  722. Interrupts
  723.  
  724.         Interrupt status is not defined
  725.         Fast interrupts are enabled
  726.  
  727. Processor mode
  728.  
  729.         Processor is in SVC mode
  730.  
  731. Re-entrancy
  732.  
  733.         SWI is not re-entrant
  734.  
  735. Use
  736.  
  737.         This call will partially compact Dynamite's heap.  It may fail
  738.         (returning C set) if either the heap is already compact, or if the
  739.         heap is locked.  Calling Dynamite_Reduce in a loop until it returns
  740.         with C set will result in the heap being fully compacted.
  741.  
  742.         This SWI may cause blocks to move within the Dynamite heap.
  743.  
  744. Related SWIs
  745.  
  746.         * Dynamite_Compact
  747.  
  748. Dynamite_Compact (SWI &4A3CA)
  749.  
  750.         Fully compacts the Dynamite heap
  751.  
  752. On entry
  753.  
  754.         --
  755.  
  756. On exit
  757.  
  758.         C set if no action performed, clear otherwise
  759.  
  760. Interrupts
  761.  
  762.         Interrupt status is not defined
  763.         Fast interrupts are enabled
  764.  
  765. Processor mode
  766.  
  767.         Processor is in SVC mode
  768.  
  769. Re-entrancy
  770.  
  771.         SWI is not re-entrant
  772.  
  773. Use
  774.  
  775.         This routine will fully compact Dynamite's heap, returning any free
  776.         space to the operating system.  It may fail (returning C set) either
  777.         if the heap is already compact, or if the heap is locked.
  778.  
  779.         This SWI may cause blocks to move within the Dynamite heap.
  780.  
  781. Related SWIs
  782.  
  783.         * Dynamite_Reduce
  784.  
  785.  
  786. Dynamite_Lock (SWI &4A3CB)
  787.  
  788.         Locks the heap, preventing blocks from moving
  789.  
  790. On entry
  791.  
  792.         --
  793.  
  794. On exit
  795.  
  796.         --
  797.  
  798. Interrupts
  799.  
  800.         Interrupt status is not defined
  801.         Fast interrupts are enabled
  802.  
  803. Processor mode
  804.  
  805.         Processor is in SVC mode
  806.  
  807. Re-entrancy
  808.  
  809.         SWI is not re-entrant
  810.  
  811. Use
  812.  
  813.         This call will lock the Dynamite heap, so that blocks will not
  814.         normally be moved around (e.g. during compaction).  Blocks may still
  815.         be moved when they are resized, however.  The heap may be unlocked
  816.         again by calling Dynamite_Unlock.  Calls to Dynamite_Lock may be
  817.         nested.
  818.  
  819.         When locked, the heap behaves much like a normal nonshifting heap,
  820.         and can become fragmented.
  821.  
  822. Related SWIs
  823.  
  824.         * Dynamite_Unlock
  825.  
  826.  
  827. Dynamite_Unlock (SWI &4A3CC)
  828.  
  829.         Unlocks the Dynamite heap
  830.  
  831. On entry
  832.  
  833.         --
  834.  
  835. On exit
  836.  
  837.         --
  838.  
  839. Interrupts
  840.  
  841.         Interrupt status is not defined
  842.         Fast interrupts are enabled
  843.  
  844. Processor mode
  845.  
  846.         Processor is in SVC mode
  847.  
  848. Re-entrancy
  849.  
  850.         SWI is not re-entrant
  851.  
  852. Use
  853.  
  854.         This call will cancel the effects of a previous Dynamite_Lock.
  855.  
  856. Related SWIs
  857.  
  858.         * Dynamite_Lock
  859.  
  860.  
  861. Dynamite_ClaimAnchor (SWI &4A3CD)
  862.  
  863.         Allocates an anchor from the RMA
  864.  
  865. On entry
  866.  
  867.         --
  868.  
  869. On exit
  870.  
  871.         R0 = address of anchor
  872.  
  873. Interrupts
  874.  
  875.         Interrupt status is not defined
  876.         Fast interrupts are enabled
  877.  
  878. Processor mode
  879.  
  880.         Processor is in SVC mode
  881.  
  882. Re-entrancy
  883.  
  884.         SWI is not re-entrant
  885.  
  886. Use
  887.  
  888.         Allocates an anchor from the RMA.  This should be used by
  889.         applications to obtain anchors, so that Dynamite does not try to
  890.         access application memory which has been paged out when it moves
  891.         blocks.
  892.  
  893. Related SWIs
  894.  
  895.         * Dynamite_ReleaseAnchor
  896.  
  897.  
  898. Dynamite_ReleaseAnchor (SWI &4A3CE)
  899.  
  900.         Releases an anchor allocated by Dynamite_ClaimAnchor
  901.  
  902. On entry
  903.  
  904.         R0 = address of anchor
  905.  
  906. On exit
  907.  
  908.         --
  909.  
  910. Interrupts
  911.  
  912.         Interrupt status is not defined
  913.         Fast interrupts are enabled
  914.  
  915. Processor mode
  916.  
  917.         Processor is in SVC mode
  918.  
  919. Re-entrancy
  920.  
  921.         SWI is not re-entrant
  922.  
  923. Use
  924.  
  925.         This SWI will allow you to release an anchor you claimed with
  926.         Dynamite_ClaimAnchor, so it can be used again.
  927.  
  928. Related SWIs
  929.  
  930.         * Dynamite_ClaimAnchor
  931.  
  932.  
  933. Dynamite_ReadSpriteSize (SWI &4A3CF)
  934.  
  935.         Reads the total size of the System Sprite Area
  936.  
  937. On entry
  938.  
  939.         --
  940.  
  941. On exit
  942.  
  943.         R0 = size of the System Sprite Area in bytes
  944.  
  945. Interrupts
  946.  
  947.         Interrupt status is undefined
  948.         Fast interrupts are enabled
  949.  
  950. Processor mode
  951.  
  952.         Processor is in SVC mode
  953.  
  954. Re-entrancy
  955.  
  956.         SWI is re-entrant
  957.  
  958. Use
  959.  
  960.         This SWI returns the size of the System Sprite Area in bytes,
  961.         including the Dynamite area if present.  It is anticipated that
  962.         programs requiring to enumerate the allocation of all memory in the
  963.         system will use code similar to the following to read the Sprite
  964.         Area size:
  965.  
  966.                 ; --- Read sprite area size ---
  967.  
  968.                 SWI     XDynamite_ReadSpriteSize
  969.                 MOVVC   R1,R0
  970.                 MOVVS   R0,#3
  971.                 SWIVS   XOS_ReadDynamicArea
  972.  
  973.  
  974. Related SWIs
  975.  
  976.         None.
  977.  
  978.  
  979. Dynamite_Describe (SWI &4A3D0)
  980.  
  981.         Describes the Dynamite area at the time of the call
  982.         
  983. On entry
  984.  
  985.         Ö
  986.         
  987. On exit
  988.  
  989.         R0 = handle of dynamic area, or -1 for pre-RISC OS 3.5 machines
  990.         R1 = total size of Dynamite area
  991.         R2 = size of unused area
  992.         
  993. Interrupts
  994.  
  995.         Interrupt status is undefined
  996.         Fast interrupts are enabled
  997.         
  998. Processor mode
  999.  
  1000.         Processor is in SVC mode
  1001.         
  1002. Re-entrancy
  1003.  
  1004.         SWI is re-entrant
  1005.         
  1006. Use
  1007.  
  1008.         This call returns some information on the Dynamite area. The sizes
  1009.         returned are only valid for the time that the caller has control and 
  1010.         doesn't call another Dynamite SWI.
  1011.  
  1012. Related SWIs
  1013.  
  1014.         None.
  1015.